home *** CD-ROM | disk | FTP | other *** search
/ MacHack 1997 / MacHack 1997.toast / Hacks / Hacks ’97 / Finder Dungeon / source code / MoreFiles 1.4.6 / C Headers / MoreDesktopMgr.h < prev    next >
Encoding:
C/C++ Source or Header  |  1997-06-28  |  19.8 KB  |  540 lines  |  [TEXT/MPS ]
  1. /*
  2. **    Apple Macintosh Developer Technical Support
  3. **
  4. **    A collection of useful high-level Desktop Manager routines.
  5. **    If the Desktop Manager isn't available, use the Desktop file
  6. **    for 'read' operations.
  7. **
  8. **    We do more because we can...
  9. **
  10. **    by Jim Luther and Nitin Ganatra, Apple Developer Technical Support Emeriti
  11. **
  12. **    File:    MoreDesktopMgr.h
  13. **
  14. **    Copyright © 1992-1996 Apple Computer, Inc.
  15. **    All rights reserved.
  16. **
  17. **    You may incorporate this sample code into your applications without
  18. **    restriction, though the sample code has been provided "AS IS" and the
  19. **    responsibility for its operation is 100% yours.  However, what you are
  20. **    not permitted to do is to redistribute the source as "DSC Sample Code"
  21. **    after having made changes. If you're going to re-distribute the source,
  22. **    we require that you make it clear in the source that the code was
  23. **    descended from Apple Sample Code, but that you've made changes.
  24. */
  25.  
  26. #ifndef __MOREDESKTOPMGR__
  27. #define __MOREDESKTOPMGR__
  28.  
  29. #include <Types.h>
  30. #include <Files.h>
  31.  
  32. #include "Optimization.h"
  33.  
  34. #ifdef __cplusplus
  35. extern "C" {
  36. #endif
  37.  
  38. /*****************************************************************************/
  39.  
  40. pascal    OSErr    DTOpen(ConstStr255Param volName,
  41.                        short vRefNum,
  42.                        short *dtRefNum,
  43.                        Boolean *newDTDatabase);
  44. /*    ¶ Open a volume's desktop database and return the desktop database refNum.
  45.     The DTOpen function opens a volume's desktop database. It returns
  46.     the reference number of the desktop database and indicates if the
  47.     desktop database was created as a result of this call (if it was created,
  48.     then it is empty).
  49.  
  50.     volName            input:    A pointer to the name of a mounted volume
  51.                             or nil.
  52.     vRefNum            input:    Volume specification.
  53.     dtRefNum        output:    The reference number of Desktop Manager's
  54.                             desktop database on the specified volume.
  55.     newDTDatabase    output:    true if the desktop database was created as a
  56.                             result of this call and thus empty.
  57.                             false if the desktop database was already created,
  58.                             or if it could not be determined if it was already
  59.                             created.
  60.     
  61.     Result Codes
  62.         noErr                0        No error
  63.         nsvErr                -35        Volume not found
  64.         ioErr                -36        I/O error
  65.         paramErr            -50        Volume doesn't support this function
  66.         extFSErr            -58        External file system error - no file
  67.                                     system claimed this call.
  68.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  69.                                     the Finder will fix this, but if your
  70.                                     application is not running with the
  71.                                     Finder, use PBDTReset or PBDTDelete
  72. */
  73.  
  74. /*****************************************************************************/
  75.  
  76. pascal    OSErr    DTXGetAPPL(ConstStr255Param volName,
  77.                            short vRefNum,
  78.                            OSType creator,
  79.                            Boolean searchCatalog,
  80.                            short *applVRefNum,
  81.                            long *applParID,
  82.                            Str255 applName);
  83. /*    ¶ Find an application on a volume that can open a file with a given creator.
  84.     The DTXGetAPPL function finds an application (file type 'APPL') with
  85.     the specified creator on the specified volume. It first tries to get
  86.     the application mapping from the desktop database. If that fails,
  87.     then it tries to find an application in the Desktop file. If that
  88.     fails and searchCatalog is true, then it tries to find an application
  89.     with the specified creator using the File Manager's CatSearch routine. 
  90.  
  91.     volName            input:    A pointer to the name of a mounted volume
  92.                             or nil.
  93.     vRefNum            input:    Volume specification.
  94.     creator            input:    The file's creator type.
  95.     searchCatalog    input:    If true, search the catalog for the application
  96.                             if it isn't found in the desktop database.
  97.     applVRefNum        output:    The volume reference number of the volume the
  98.                             application is on.
  99.     applParID        output:    The parent directory ID of the application.
  100.     applName        output:    The name of the application.
  101.     
  102.     Result Codes
  103.         noErr                0        No error
  104.         nsvErr                -35        Volume not found
  105.         ioErr                -36        I/O error
  106.         paramErr            -50        No default volume
  107.         rfNumErr            -51        Reference number invalid
  108.         extFSErr            -58        External file system error - no file
  109.                                     system claimed this call
  110.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  111.                                     the Finder will fix this, but if your
  112.                                     application is not running with the
  113.                                     Finder, use PBDTReset or PBDTDelete
  114.         afpItemNotFound        -5012    Information not found
  115.     
  116.     __________
  117.     
  118.     Also see:    FSpDTGetAPPL
  119. */
  120.  
  121. /*****************************************************************************/
  122.  
  123. pascal    OSErr    FSpDTXGetAPPL(ConstStr255Param volName,
  124.                               short vRefNum,
  125.                               OSType creator,
  126.                               Boolean searchCatalog,
  127.                               FSSpec *spec);
  128. /*    ¶ Find an application on a volume that can open a file with a given creator.
  129.     The FSpDTXGetAPPL function finds an application (file type 'APPL') with
  130.     the specified creator on the specified volume. It first tries to get
  131.     the application mapping from the desktop database. If that fails,
  132.     then it tries to find an application in the Desktop file. If that
  133.     fails and searchCatalog is true, then it tries to find an application
  134.     with the specified creator using the File Manager's CatSearch routine. 
  135.  
  136.     volName            input:    A pointer to the name of a mounted volume
  137.                             or nil.
  138.     vRefNum            input:    Volume specification.
  139.     creator            input:    The file's creator type.
  140.     searchCatalog    input:    If true, search the catalog for the application
  141.                             if it isn't found in the desktop database.
  142.     spec            output:    FSSpec record containing the application name and
  143.                             location.
  144.     
  145.     Result Codes
  146.         noErr                0        No error
  147.         nsvErr                -35        Volume not found
  148.         ioErr                -36        I/O error
  149.         paramErr            -50        No default volume
  150.         rfNumErr            -51        Reference number invalid
  151.         extFSErr            -58        External file system error - no file
  152.                                     system claimed this call
  153.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  154.                                     the Finder will fix this, but if your
  155.                                     application is not running with the
  156.                                     Finder, use PBDTReset or PBDTDelete
  157.         afpItemNotFound        -5012    Information not found
  158.     
  159.     __________
  160.     
  161.     Also see:    FSpDTGetAPPL
  162. */
  163.  
  164. /*****************************************************************************/
  165.  
  166. pascal    OSErr    DTGetAPPL(ConstStr255Param volName,
  167.                           short vRefNum,
  168.                           OSType creator,
  169.                           short *applVRefNum,
  170.                           long *applParID,
  171.                           Str255 applName);
  172. /*    ¶ Find an application on a volume that can open a file with a given creator.
  173.     The DTGetAPPL function finds an application (file type 'APPL') with
  174.     the specified creator on the specified volume. It first tries to get
  175.     the application mapping from the desktop database. If that fails,
  176.     then it tries to find an application in the Desktop file. If that
  177.     fails, then it tries to find an application with the specified creator
  178.     using the File Manager's CatSearch routine. 
  179.  
  180.     volName        input:    A pointer to the name of a mounted volume
  181.                         or nil.
  182.     vRefNum        input:    Volume specification.
  183.     creator        input:    The file's creator type.
  184.     applVRefNum    output:    The volume reference number of the volume the
  185.                         application is on.
  186.     applParID    output:    The parent directory ID of the application.
  187.     applName    output:    The name of the application.
  188.     
  189.     Result Codes
  190.         noErr                0        No error
  191.         nsvErr                -35        Volume not found
  192.         ioErr                -36        I/O error
  193.         paramErr            -50        No default volume
  194.         rfNumErr            -51        Reference number invalid
  195.         extFSErr            -58        External file system error - no file
  196.                                     system claimed this call
  197.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  198.                                     the Finder will fix this, but if your
  199.                                     application is not running with the
  200.                                     Finder, use PBDTReset or PBDTDelete
  201.         afpItemNotFound        -5012    Information not found
  202.     
  203.     __________
  204.     
  205.     Also see:    FSpDTGetAPPL
  206. */
  207.  
  208. /*****************************************************************************/
  209.  
  210. pascal    OSErr    FSpDTGetAPPL(ConstStr255Param volName,
  211.                              short vRefNum,
  212.                              OSType creator,
  213.                              FSSpec *spec);
  214. /*    ¶ Find an application on a volume that can open a file with a given creator.
  215.     The FSpDTGetAPPL function finds an application (file type 'APPL') with
  216.     the specified creator on the specified volume. It first tries to get
  217.     the application mapping from the desktop database. If that fails,
  218.     then it tries to find an application in the Desktop file. If that
  219.     fails, then it tries to find an application with the specified creator
  220.     using the File Manager's CatSearch routine. 
  221.  
  222.     volName        input:    A pointer to the name of a mounted volume
  223.                         or nil.
  224.     vRefNum        input:    Volume specification.
  225.     creator        input:    The file's creator type.
  226.     spec        output:    FSSpec record containing the application name and
  227.                         location.
  228.     
  229.     Result Codes
  230.         noErr                0        No error
  231.         nsvErr                -35        Volume not found
  232.         ioErr                -36        I/O error
  233.         paramErr            -50        No default volume
  234.         rfNumErr            -51        Reference number invalid
  235.         extFSErr            -58        External file system error - no file
  236.                                     system claimed this call
  237.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  238.                                     the Finder will fix this, but if your
  239.                                     application is not running with the
  240.                                     Finder, use PBDTReset or PBDTDelete
  241.         afpItemNotFound        -5012    Information not found
  242.     
  243.     __________
  244.     
  245.     Also see:    DTGetAPPL
  246. */
  247.  
  248. /*****************************************************************************/
  249.  
  250. pascal    OSErr    DTGetIcon(ConstStr255Param volName,
  251.                           short vRefNum,
  252.                           short iconType,
  253.                           OSType fileCreator,
  254.                           OSType fileType,
  255.                           Handle *iconHandle);
  256. /*    ¶ Get an icon from the desktop database or Desktop file.
  257.     The DTGetIcon function retrieves the specified icon and returns it in
  258.     a newly created handle. The icon is retrieves from the Desktop Manager
  259.     or if the Desktop Manager is not available, from the Finder's Desktop
  260.     file. Your program is responsible for disposing of the handle when it is
  261.     done using the icon.
  262.  
  263.     volName        input:    A pointer to the name of a mounted volume
  264.                         or nil.
  265.     vRefNum        input:    Volume specification.
  266.     iconType    input:    The icon type as defined in Files.h. Valid values are:
  267.                             kLargeIcon
  268.                             kLarge4BitIcon
  269.                             kLarge8BitIcon
  270.                             kSmallIcon
  271.                             kSmall4BitIcon
  272.                             kSmall8BitIcon
  273.     fileCreator    input:    The icon's creator type.
  274.     fileType    input:    The icon's file type.
  275.     iconHandle    output:    A Handle containing the newly created icon.
  276.     
  277.     Result Codes
  278.         noErr                0        No error
  279.         nsvErr                -35        Volume not found
  280.         ioErr                -36        I/O error
  281.         paramErr            -50        Volume doesn't support this function
  282.         rfNumErr            -51        Reference number invalid
  283.         extFSErr            -58        External file system error - no file
  284.                                     system claimed this call
  285.         memFullErr            -108    iconHandle could not be allocated
  286.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  287.                                     the Finder will fix this, but if your
  288.                                     application is not running with the
  289.                                     Finder, use PBDTReset or PBDTDelete
  290.         afpItemNotFound        -5012    Information not found
  291. */
  292.  
  293. /*****************************************************************************/
  294.  
  295. pascal    OSErr    DTSetComment(short vRefNum,
  296.                              long dirID,
  297.                              ConstStr255Param name,
  298.                              ConstStr255Param comment);
  299. /*    ¶ Set a file or directory's Finder comment field.
  300.     The DTSetComment function sets a file or directory's Finder comment
  301.     field. The volume must support the Desktop Manager because you only
  302.     have read access to the Desktop file.
  303.  
  304.     vRefNum    input:    Volume specification.
  305.     dirID    input:    Directory ID.
  306.     name    input:    Pointer to object name, or nil when dirID
  307.                     specifies a directory that's the object.
  308.     comment    input:    The comment to add. Comments are limited to 200 characters;
  309.                     longer comments are truncated.
  310.     
  311.     Result Codes
  312.         noErr                0        No error
  313.         nsvErr                -35        Volume not found
  314.         ioErr                -36        I/O error
  315.         fnfErr                –43        File or directory doesn’t exist
  316.         paramErr            -50        Volume doesn't support this function
  317.         wPrErr                –44        Volume is locked through hardware
  318.         vLckdErr            –46        Volume is locked through software
  319.         rfNumErr            –51        Reference number invalid
  320.         extFSErr            -58        External file system error - no file
  321.                                     system claimed this call.
  322.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  323.                                     the Finder will fix this, but if your
  324.                                     application is not running with the
  325.                                     Finder, use PBDTReset or PBDTDelete
  326.     
  327.     __________
  328.     
  329.     Also see:    DTCopyComment, FSpDTCopyComment, FSpDTSetComment, DTGetComment,
  330.                 FSpDTGetComment
  331. */
  332.  
  333. /*****************************************************************************/
  334.  
  335. pascal    OSErr    FSpDTSetComment(const FSSpec *spec,
  336.                                 ConstStr255Param comment);
  337. /*    ¶ Set a file or directory's Finder comment field.
  338.     The FSpDTSetComment function sets a file or directory's Finder comment
  339.     field. The volume must support the Desktop Manager because you only
  340.     have read access to the Desktop file.
  341.  
  342.     spec    input:    An FSSpec record specifying the file or directory.
  343.     comment    input:    The comment to add. Comments are limited to 200 characters;
  344.                     longer comments are truncated.
  345.     
  346.     Result Codes
  347.         noErr                0        No error
  348.         nsvErr                -35        Volume not found
  349.         ioErr                -36        I/O error
  350.         fnfErr                –43        File or directory doesn’t exist
  351.         wPrErr                –44        Volume is locked through hardware
  352.         vLckdErr            –46        Volume is locked through software
  353.         rfNumErr            –51        Reference number invalid
  354.         paramErr            -50        Volume doesn't support this function
  355.         extFSErr            -58        External file system error - no file
  356.                                     system claimed this call.
  357.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  358.                                     the Finder will fix this, but if your
  359.                                     application is not running with the
  360.                                     Finder, use PBDTReset or PBDTDelete
  361.     
  362.     __________
  363.     
  364.     Also see:    DTCopyComment, FSpDTCopyComment, DTSetComment, DTGetComment,
  365.                 FSpDTGetComment
  366. */
  367.  
  368. /*****************************************************************************/
  369.  
  370. pascal    OSErr    DTGetComment(short vRefNum,
  371.                              long dirID,
  372.                              ConstStr255Param name,
  373.                              Str255 comment);
  374. /*    ¶ Get a file or directory's Finder comment field (if any).
  375.     The DTGetComment function gets a file or directory's Finder comment
  376.     field (if any) from the Desktop Manager or if the Desktop Manager is
  377.     not available, from the Finder's Desktop file.
  378.  
  379.     IMPORTANT NOTE: Inside Macintosh says that comments are up to
  380.     200 characters. While that may be correct for the HFS file system's
  381.     Desktop Manager, other file systems (such as Apple Photo Access) return
  382.     up to 255 characters. Make sure the comment buffer is a Str255 or you'll
  383.     regret it.
  384.     
  385.     vRefNum    input:    Volume specification.
  386.     dirID    input:    Directory ID.
  387.     name    input:    Pointer to object name, or nil when dirID
  388.                     specifies a directory that's the object.
  389.     comment    output:    A Str255 where the comment is to be returned.
  390.     
  391.     Result Codes
  392.         noErr                0        No error
  393.         nsvErr                -35        Volume not found
  394.         ioErr                -36        I/O error
  395.         paramErr            -50        Volume doesn't support this function
  396.         rfNumErr            –51        Reference number invalid
  397.         extFSErr            -58        External file system error - no file
  398.                                     system claimed this call.
  399.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  400.                                     the Finder will fix this, but if your
  401.                                     application is not running with the
  402.                                     Finder, use PBDTReset or PBDTDelete
  403.         afpItemNotFound        -5012    Information not found
  404.         
  405.     __________
  406.     
  407.     Also see:    DTCopyComment, FSpDTCopyComment, DTSetComment, FSpDTSetComment,
  408.                 FSpDTGetComment
  409. */
  410.  
  411. /*****************************************************************************/
  412.  
  413. pascal    OSErr    FSpDTGetComment(const FSSpec *spec,
  414.                                 Str255 comment);
  415. /*    ¶ Get a file or directory's Finder comment field (if any).
  416.     The FSpDTGetComment function gets a file or directory's Finder comment
  417.     field (if any) from the Desktop Manager or if the Desktop Manager is
  418.     not available, from the Finder's Desktop file.
  419.  
  420.     IMPORTANT NOTE: Inside Macintosh says that comments are up to
  421.     200 characters. While that may be correct for the HFS file system's
  422.     Desktop Manager, other file systems (such as Apple Photo Access) return
  423.     up to 255 characters. Make sure the comment buffer is a Str255 or you'll
  424.     regret it.
  425.     
  426.     spec    input:    An FSSpec record specifying the file or directory.
  427.     comment    output:    A Str255 where the comment is to be returned.
  428.  
  429.     Result Codes
  430.         noErr                0        No error
  431.         nsvErr                -35        Volume not found
  432.         ioErr                -36        I/O error
  433.         paramErr            -50        Volume doesn't support this function
  434.         rfNumErr            –51        Reference number invalid
  435.         extFSErr            -58        External file system error - no file
  436.                                     system claimed this call.
  437.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  438.                                     the Finder will fix this, but if your
  439.                                     application is not running with the
  440.                                     Finder, use PBDTReset or PBDTDelete
  441.         afpItemNotFound        -5012    Information not found
  442.         
  443.     __________
  444.     
  445.     Also see:    DTCopyComment, FSpDTCopyComment, DTSetComment, FSpDTSetComment,
  446.                 DTGetComment
  447. */
  448.  
  449. /*****************************************************************************/
  450.  
  451. pascal    OSErr    DTCopyComment(short srcVRefNum,
  452.                               long srcDirID,
  453.                               ConstStr255Param srcName,
  454.                               short dstVRefNum,
  455.                               long dstDirID,
  456.                               ConstStr255Param dstName);
  457. /*    ¶ Copy the file or folder comment from the source to the destination object.
  458.     The DTCopyComment function copies the file or folder comment from the
  459.     source to the destination object.  The destination volume must support
  460.     the Desktop Manager because you only have read access to the Desktop file.
  461.     
  462.     srcVRefNum    input:    Source volume specification.
  463.     srcDirID    input:    Source directory ID.
  464.     srcName        input:    Pointer to source object name, or nil when srcDirID
  465.                         specifies a directory that's the object.
  466.     dstVRefNum    input:    Destination volume specification.
  467.     dstDirID    input:    Destination directory ID.
  468.     dstName        input:    Pointer to destination object name, or nil when
  469.                         dstDirID specifies a directory that's the object.
  470.     
  471.     Result Codes
  472.         noErr                0        No error
  473.         nsvErr                -35        Volume not found
  474.         ioErr                -36        I/O error
  475.         fnfErr                –43        File or directory doesn’t exist
  476.         wPrErr                –44        Volume is locked through hardware
  477.         vLckdErr            –46        Volume is locked through software
  478.         paramErr            -50        Volume doesn't support this function
  479.         rfNumErr            –51        Reference number invalid
  480.         paramErr            -50        Volume doesn't support this function
  481.         extFSErr            -58        External file system error - no file
  482.                                     system claimed this call.
  483.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  484.                                     the Finder will fix this, but if your
  485.                                     application is not running with the
  486.                                     Finder, use PBDTReset or PBDTDelete
  487.         afpItemNotFound        -5012    Information not found
  488.         
  489.     __________
  490.     
  491.     Also see:    FSpDTCopyComment, DTSetComment, FSpDTSetComment, DTGetComment,
  492.                 FSpDTGetComment
  493. */
  494.  
  495. /*****************************************************************************/
  496.  
  497. pascal    OSErr    FSpDTCopyComment(const FSSpec *srcSpec,
  498.                                  const FSSpec *dstSpec);
  499. /*    ¶ Copy the desktop database comment from the source to the destination object.
  500.     The FSpDTCopyComment function copies the desktop database comment from
  501.     the source to the destination object.  Both the source and the
  502.     destination volumes must support the Desktop Manager.
  503.     
  504.     srcSpec        input:    An FSSpec record specifying the source object.
  505.     dstSpec        input:    An FSSpec record specifying the destination object.
  506.     
  507.     Result Codes
  508.         noErr                0        No error
  509.         nsvErr                -35        Volume not found
  510.         ioErr                -36        I/O error
  511.         fnfErr                –43        File or directory doesn’t exist
  512.         wPrErr                –44        Volume is locked through hardware
  513.         vLckdErr            –46        Volume is locked through software
  514.         paramErr            -50        Volume doesn't support this function
  515.         rfNumErr            –51        Reference number invalid
  516.         paramErr            -50        Volume doesn't support this function
  517.         extFSErr            -58        External file system error - no file
  518.                                     system claimed this call.
  519.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  520.                                     the Finder will fix this, but if your
  521.                                     application is not running with the
  522.                                     Finder, use PBDTReset or PBDTDelete
  523.         afpItemNotFound        -5012    Information not found
  524.         
  525.     __________
  526.     
  527.     Also see:    DTCopyComment, DTSetComment, FSpDTSetComment, DTGetComment,
  528.                 FSpDTGetComment
  529. */
  530.  
  531. /*****************************************************************************/
  532.  
  533. #ifdef __cplusplus
  534. }
  535. #endif
  536.  
  537. #include "OptimizationEnd.h"
  538.  
  539. #endif    /* __MOREDESKTOPMGR__ */
  540.